Size Change: +5.45 kB (+1%)

Total Size: 1.04 MB

_{compressed-size-action}

@ellatrix This config doesn't seem to work in the site editor for some reason, not sure I understand why.

I find this concept more confusing than simply having margin support.

Nice, thanks for working on this. I'm a big fan of gap! (See also #32366).

As far as the instructions in this PR, this also works as advertised, however it doesn't appear to be the gap that I was expecting. I'm getting this:

.editor-styles-wrapper .edit-post-visual-editor__post-title-wrapper > * + *, .editor-styles-wrapper .block-editor-block-list__layout.is-root-container > * + * {
    margin-top: var( --wp-theme-block-gap );
    margin-bottom: 0;
}

Would I get true gap if I set my layout to be a flex or grid container?

The margin-based gap as I see here is useful enough on its own, but the reason I'm longing for "true" gap is that it lets you stop worry about first-child/last-child margins entirely. I often compare it to Figma's auto-layout:

Basically with using only padding and gap (Figma calls it "Space between items"), you can quite easily create consistent spacing. This is especially useful in masonry galleries, where you might have to tackle gnarly nth-child rules.

This is inspired by on some advanced layout work you can read about here https://every-layout.dev/layouts/stack/
The gap only works in flex containers and for "flex" layout, that's exactly what we'll be using, but for "flow" layout, that trick is needed and it solves all the last-child/first-child issues.

I find this concept more confusing than simply having margin support.

Margin is not something that will solve this issue consistently, theme authors will need to be able to target, first and last blocks... Also, it doesn't scale well to all types of layouts.

The key mental shift here is that margin, conceptualized as the spacing between blocks, is something extrinsic to the block itself and better imagined as a property of the container. Individual blocks can overwrite margin values, but it should be sporadic and considered more advanced (it can be difficult to handle for a user and break visual rhythm).

I think we might want to avoid gap to designated it, though, and lean more strongly on the "block" property. The description should be "Set the spacing between blocks". For the property perhaps spacing.blocks is fine? If we want to keep gap, maybe it should be blockGap.

Having control over this globally and per container should simplify how you need to deal with blocks and margins, as it should handle dealing with the top / bottom blocks by default, which has been a bit painful in columns already. In the "spacing" panel we should also be clear when a block is overwriting the default gap setting.

I added support for the blockGap to the flex layout as well.

I think this looks very cool, I like the idea of using gap to control the spacing between blocks, and the CSS variable approach looks like a clever way to do it!

No UI/block support has been added for now,

Separately, I've been chipping away at a PR to add in a gap block support feature in #33991 as a way of trying to come up with a solution for #32366. My PR is split out from the ToolsPanel / DimensionsPanel work in #32392 and adds in UI / block support with a BoxControl in the inspector controls and global styles for controlling the gap. I was imagining this as a way of handling gap (and row-gap and column-gap for control over separate vertical and horizontal spacing) for blocks like Buttons, Navigation, Social Links, and possibly longer term the Gallery block. It's implemented in a similar way to margin and padding, but might not be the right way to go about it.

It looks like this PR will provide a more general solution and approach for layouts, so it looks like it might supersede my one. But I just thought I'd check in case there's anything useful in #33991 that you might want to pull in here or if there's a way to combine things. I'm happy to help any way I can!

With this PR, do you imagine the layout types will be rolled out to all other container blocks (e.g. Buttons, etc) or would we have a different approach for those sorts of blocks versus, say Group? It could also be good to include the ability to separately control row vs column gap, depending on where we roll the feature out, to support different kinds of layouts.

Thank you, that's helpful! Sounds like the CSS-first refactor can move forward and be revisited further.

I don't think we have that yet but the use-cases for it are not clear yet. The issue you mentioned was a bug that is now closed. The block gets "flex" if the default layout is defined as "flex".

I ran into wanting to create a classic header menu that featured a site logo and a navigation block left and right as part of the Header template part, and finding that the stack-margin ruleset was applied even though I went for a horizontal layout:

But that use case is already met by #33316, since this can now just be a single navigation block inside the header. But it does support the separate conversation we were having about allowing the group block to become a horizontal flex container.

A thing I noticed as well. We output only the .wp-site-blocks > * + * rule which zeroes out the bottom margin and applies the top margin as a gap. We don't output a matching .wp-site-blocks > * { margin-top: 0; margin-bottom: 0; }; to take care of the first block in the stack:

Since in vertical flows, those margins commonly collapse, it's been fine so far. But it seems like we should? I can open a separate ticket.

I think that makes sense 👍

From #33991, I got the impression that this feature is opt-in with settings.spacing.blockGap, but it seems like the .wp-container-XXX > * + * margin styles are output in 11.4.0 regardless of whether settings.spacing.blockGap exists or is set to false. Just double-checking if that's intentional.

The current reasoning is that it's intentional, the style is not opt-in, the per block UI is.

Got it. That might cause some issues for themes that have different margins for different elements (for example, larger margin for headings, tables, separators etc. than paragraphs) and at different breakpoints, since the specificity on the styles overwriting .wp-container-XXX > * + * needs to be very high.

it only applies to themes with theme.json though which I think has just been release on 5.8. So hopefully not a lot of themes. The dev note is supposed to clarify that. Do you think that's a fine shipping plan?

I'm also curious about the use-case. Would things like this solve it?

styles: {
   core/heading: {
       margin: "some value" 
   }
}

I'm also thinking it might not be the best approach because we don't want that "margin" value when the block is inside a horizontal/flex container for instance.

I think being able to opt out would lower the barrier for existing themes adding theme.json pretty significantly, since most themes would probably need to modify their margin styles a lot to overwrite the default gap value (in the cases where they want to overwrite them). I think there are cases where themes built with theme.json from the ground up would want to opt out as well, if many elements in the design have different margins for different breakpoints.

I'm also curious about the use-case. Would things like this solve it?

Being able to set the gap on a block level would definitely go a long way.

I'll ask for some input in the theme review channel on Slack.

I think there are cases where themes built with theme.json from the ground up would want to opt out as well, if many elements in the design have different margins for different breakpoints.

The issue I have with this is that blocks shouldn't have intrinsic margins because blocks shouldn't be assuming that they are inserted in a "flow" container, they can be on a flex container, horizontal... and those margins won't make sense anymore. I don't think a theme author should have the responsibility to define all these use-cases because it will break very quickly.

We can add a way to "not output these styles", but I fear that this is just making things worse for themes and break some blocks in different contexts. So how to solve this use-case more holistically?

Got it. That might cause some issues for themes that have different margins for different elements (for example, larger margin for headings, tables, separators etc. than paragraphs) and at different breakpoints, since the specificity on the styles overwriting .wp-container-XXX > * + * needs to be very high.

I just checked this and [class*="wp-container-"] .block-selector is enough to override this rule. I'd want to control the margins of the blocks via theme.json like so. I get the problem when the block is in a flex group. My experience is that we want to establish defaults on a vertical level and then make exceptions on the horizontal one most of the time, but that might not be a good way to go about it.

Yeah, it's a difficult balance to strike. Most theme authors will want to have some degree of control over margins though, at least on the base element level (paragraphs, lists, headings, etc.), and it can pretty quickly lead to specificity wars.

For example, the margin styles generated for the h1 element by the code below get overwritten by the new .wp-container-XXX > * + * styles in 11.4.0:

"styles": {
	"elements": {
		"h1": {
			"spacing": {
				"margin": {
					"bottom": "48px",
					"top": "64px"
				}
			},
			"typography": {
				"fontSize": "var(--wp--preset--font-size--heading-1)",
				"letterSpacing": "var(--wp--custom--letter-spacing--heading)",
				"lineHeight": "var(--wp--custom--line-height--heading)",
				"fontWeight": "var(--wp--custom--font-weight--normal)"
			}
		},
	}
}

So if a theme would want to have a different margin than the blockGap for h1, they would need to add CSS looking something like this to overwrite it:

:root h1 {
	margin-bottom: 48px;
	margin-top: 64px;
}

Should theme authors be able to opt-out? If this is ever a question that comes up, the answer is always: Absolutely, 100%, yes!

The only assumption we should make is that a theme author will want to do something custom. If we start from that position, these sorts of conversations will happen less often.

This block gap feature has created issues across the board for me. My plan is to work with it as much as possible, but I am already seeing places where it will be problematic and force specificity battles.

Doing this in a per-block level would ease some of that. For example, my Heading elements tend to have a different top margin than Paragraph elements (this was actually the first thing I noticed that was broken).

Edit: On the topic of horizontal, flex, etc. containers: those are exceptions to the rule. For example, I target :first-child to remove top margins, which I think is pretty typical in design systems. This automatically handles things like the Columns/Column blocks. The same or similar methods would work in other types of containers.

Should theme authors be able to opt-out? If this is ever a question that comes up, the answer is always: Absolutely, 100%, yes!

I disagree with this take. This means that everything should be optional in WordPress and goes against the decisions not options. some things need to be options but not everything.

After the discussion we had here, I agree that for now the block gap styles need to be opt-out because we don't have answers for all the use cases yet but I don't think it should be a rule to have an opt-out for everything personally. For instance for structural styles, I'd rather have the themes rely on Core always instead of reinventing their own. Themes are here to bring personality and design but not to define what "horizontal alignment" means for instance.

This block gap feature has created issues across the board for me. My plan is to work with it as much as possible, but I am already seeing places where it will be problematic and force specificity battles.

I'd love to learn mode about the use-cases to be able to come up with the best abstractions that solve this. If we always fallback to CSS to solve these issues, specificity issues will continue forever and adaptation as Core changes structural changes will continue to be a nightmare. Theme.json is an attempt to solve that, so we should try to reduce the need for these custom CSS (other than things that bring personality) from themes.

Doing this in a per-block level would ease some of that. For example, my Heading elements tend to have a different top margin than Paragraph elements (this was actually the first thing I noticed that was broken).

👍 Yes that use-case has been raised above and makes sense but it's also important to understand that it only makes sense in the "flow" layout. If you insert a heading block inside a horizontal container, it shouldn't have any margins. For this particular reason, we need to be more smart about it:

• If it's theme author's responsibility, they'll forget about these things and create broken designs
• if it's core responsibility, we need ways to ensure these things work properly in all contexts.

I can think of other cases where you'd want a different gap per block. One example would be the "small" blocks that have post meta content such as post date or post tags, we encountered this on skatepark, where the margin bottom (or gap) for an h1 could be 5 times or more the spacing between these smaller blocks:

Seeing the recent comments here, I was dreading how this might affect the block-based theme I'm currently working on. The effects ended up being minimal due to already adopting the "styling the context" approach every-layout.dev endorses, but at a different location: the .post-content level. My experience has been header/footer areas benefit less from the same rules, due to having their own micro-contexts to manage.

A few examples from my current theme where elements require different "gaps" in a flow context:

• <h2> and <h3> following any element
• any element following a Columns block (excluding another Columns block)
• any element following a full/wide aligned element with a background colour set
• any top-level element with a background colour set following any element
• "meta" content following a heading

Should theme authors be able to opt-out? If this is ever a question that comes up, the answer is always: Absolutely, 100%, yes!

Very much agree from a theming perspective.

For instance for structural styles, I'd rather have the themes rely on Core always instead of reinventing their own.

If it's theme author's responsibility, they'll forget about these things and create broken designs. If it's core responsibility, we need ways to ensure these things work properly in all contexts.

I've gone back and forth since 5.0 with adding to core styles vs. 100% custom styles, and, overall, I've seen custom styles be the only way to achieve layouts I'm handed, as well as being the easiest to maintain over the long term (the other reason is, using custom styles has allowed me to use things like CSS Grid for layout now rather than waiting for it to appear as a WordPress-provided option).

Working with WordPress post-5.0 has meant learning to write styles in a much more defensive and resilient way, something I see as a positive outcome. However, I do often feel idiotic for writing my own style-sheets. Perhaps it's time to send a clear signal to someone like me by removing the option to dequeue core styles?

I find this concept more confusing than simply having margin support.

I would like to be able to opt out for the theme global gap and opt-in on specific blocks.

Should theme authors be able to opt-out? If this is ever a question that comes up, the answer is always: Absolutely, 100%, yes!

Yes, yes, yes!!! I think this is an absolute must, since a general rule might work for some smaller projects, but it does not leave enough choice/control for theme developers to make custom decisions.

At the moment I get the feeling in general that we might need more clarity on "what goes where" as I struggle to understand what is meant to be block 'territory' and what is theme territory and so on.
Is this just me or do others feel the same?

we don't have answers for all the use cases yet...
I'd love to learn mode about the use-cases to be able to come up with the best abstractions that solve this

I opened #34716 to start documenting use cases that need improvement